tools/qemu-wasm: PebbleOS emulator in the browser (QEMU→wasm, app install, PebbleKit JS) - #1910

Add an assembler that packs QEMU wasm, runtime JS, pthread worker, and
the release firmware into one self-contained HTML page (gzip + base64,
unpacked in-browser via DecompressionStream), with an environment probe
that reports exactly which host capability is missing (COOP/COEP,
SharedArrayBuffer, blob workers) instead of hanging on an incompatible
host. Includes a headless chromium test driving both the boot and the
diagnostics paths.

To fit single-page size limits, document the Pebble-only QEMU build:
--without-default-devices --with-devices-arm=pebble with a one-line
devices config, which drops every non-Pebble ARM board and shrinks the
wasm from 39 MB to 25 MB (13.8 MB page total). That surfaced a missing
'select I2C' in the PEBBLE Kconfig entry, now part of the refreshed
browser-glue patch.

Verified: the assembled page boots v4.35.0 emery firmware under
chromium with pixels on canvas, and renders the correct diagnostic when
served without cross-origin isolation.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Pi1WErefJ7c6kXodajm25M
Signed-off-by: Eric Migicovsky <eric@repebble.com>

Transport-only directory (see its README): the assembled emulator site
for ericmigi/pebble-qemu-wasm's GitHub Pages, so a session with push
access there can deploy without redoing the wasm build. Verified under
a headerless static host with coi-serviceworker providing isolation:
crossOriginIsolated true, firmware boots, display renders.

Remove before merging this branch.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Pi1WErefJ7c6kXodajm25M
Signed-off-by: Eric Migicovsky <eric@repebble.com>

Fold the measured wasm performance work into the browser-glue patch:

- pebble_display framebuffer becomes plain RAM (memory_region_init_ram_ptr)
  instead of trapping MMIO: guest pixel writes were tens of thousands of
  interpreted slow-path exits per frame. The CTRL_UPDATE doorbell is the
  only sync point the firmware relies on, so nothing needs to trap.
- inline TLB fast path in the TCI interpreter's tci_qemu_ld/st (ported
  from the ericmigi/pebble-qemu-wasm work): on a TLB hit with no flags,
  access host memory directly instead of the helper_*_mmu call chain.
- skip cpu_io_recompile under emscripten (longjmp is a JS exception).
- -sASYNCIFY_REMOVE for the interpreter hot path, -Doptimization=3,
  mimalloc.

Continuous launcher scroll on pebble-emery v4.35.0 under node
(4 shared cores): 2.1 -> 4.5 fps; boot to 'Ready for communication'
91 s -> 38 s; boot animation 1.3 -> 6.9 fps.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Pi1WErefJ7c6kXodajm25M
Signed-off-by: Eric Migicovsky <eric@repebble.com>

The TCI interpreter plateaus at ~4.5 fps on continuous launcher
scrolling. Port the generic-machine device set onto ktock/qemu-wasm
branch wasm64-tcg-b (QEMU 10.2.50 with the TCG WebAssembly JIT
backend), which compiles hot translation blocks to native wasm:

  boot to 'Ready for communication'  91 s -> 38 s -> 15 s
  continuous launcher scroll        2.1 -> 4.5 -> 16.9 fps
  (baseline TCI -> patched TCI -> JIT, node on 4 shared cores)

tools/qemu-wasm/jit/ carries the overlay (device set ported to the
QEMU 10.2 APIs: hw/core header moves, CharBackend->CharFrontend,
machines must declare arm_machine_interfaces to be visible in the
single-binary machine registry, pebble_audio rewritten as a
register-compatible drain-only stub since the audio subsystem was
rewritten, pebble_set_button_state moved into pebble_gpio.c), the
meson/Kconfig wiring patch, the MEMORY64=2 dependency build script,
and a README with the build recipe and the API-drift map.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Pi1WErefJ7c6kXodajm25M
Signed-off-by: Eric Migicovsky <eric@repebble.com>

Under the JIT build (-sMEMORY64=2 with WASM_BIGINT) pointer-returning
glue exports arrive in JS as BigInt, and the blit path's pointer
arithmetic throws 'Cannot mix BigInt and other types'. Wrap the two
pointer exports in Number(); a no-op for the wasm32 TCI build.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Pi1WErefJ7c6kXodajm25M
Signed-off-by: Eric Migicovsky <eric@repebble.com>

The page imported ./qemu-system-arm.mjs while every deployment lays the
emscripten output down under its original .js name; browsers resolve
module type from MIME, not extension, so standardize on .js.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Pi1WErefJ7c6kXodajm25M
Signed-off-by: Eric Migicovsky <eric@repebble.com>

Swap the deployable bundle's emulator to the TCG-to-wasm JIT build
(9 MB wasm, no separate worker file, boots to the watchface in ~15 s
at ~17 fps scrolling) and carry the updated shell. Verified booting
under a headerless static host with coi-serviceworker in chromium.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Pi1WErefJ7c6kXodajm25M
Signed-off-by: Eric Migicovsky <eric@repebble.com>

The pebble-tool channel (UART1, QemuProtocol framing) previously had no
transport in the browser build. Add an emscripten-only bridge inside
pebble_control: pebble_wasm_serial_ctrl() exports a pair of ring
buffers; the page produces host->guest bytes into the rx ring with
Atomics and a 2 ms virtual-clock timer feeds them through the normal
chardev receive path, while all watch-bound writes are mirrored into
the tx ring for the page to drain. Works alongside a real chardev, and
pebble_control is now created even when serial1 has none.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Pi1WErefJ7c6kXodajm25M
Signed-off-by: Eric Migicovsky <eric@repebble.com>

Implement the phone side of the app-install flow in JS on top of the
UART1 ring bridge:

- pebble-transport.js: QemuProtocol framing (0xFEED/0xBEEF), Pebble
  Protocol stream reassembly in both directions, and the endpoint-17
  version handshake. The response is V3 with capabilities 0xA3 because
  the firmware replaces (not ORs) session capabilities, and losing
  CommSessionRunState would break launch notifications.
- pbw.js: .pbw (zip) reader on the native DecompressionStream with
  platform-directory selection (emery -> basalt -> diorite -> aplite).
- app-install.js: BlobDB INSERT of the 126-byte AppDBEntry (retrying on
  TRY_LATER), app_run_state RUN to trigger the watch's AppFetch
  request, then PutBytes INIT/PUT/COMMIT/INSTALL per object with the
  legacy defective CRC (verified against the firmware's test vectors).
  Legacy struct-version binaries read the uuid at its pre-3.0 offset.
- store.js: resolves apps.repebble.com / apps.rebble.io links via the
  CORS-enabled appstore API and downloads the release pbw.
- index.html: install panel (paste a store link) plus drag-drop of
  .pbw files onto the page, with transfer progress.

Verified headless under node and in Chromium against the JIT build:
BlobDB ack, AppFetch round-trip, CRC-clean PutBytes commits, and the
watch launching the installed watchface (app fetch result 0).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Pi1WErefJ7c6kXodajm25M
Signed-off-by: Eric Migicovsky <eric@repebble.com>

New JIT build with the serial bridge, the install JS modules, and the
updated shell page; apply.sh now copies the module files. Document the
serial bridge and install flow in the README.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Pi1WErefJ7c6kXodajm25M
Signed-off-by: Eric Migicovsky <eric@repebble.com>

File-picker alternative to drag-drop for installing local .pbw files.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Pi1WErefJ7c6kXodajm25M
Signed-off-by: Eric Migicovsky <eric@repebble.com>

Apps with a pebble-js-app.js now get their JS executed when the watch
launches them, wired to the watch over AppMessage:

- appmessage.js: endpoint 0x30 client. PUSH carries the app uuid and a
  little-endian tuple dictionary; ACK/NACK are two bytes echoing the
  transaction id. Sends are serialized through a queue (one PUSH in
  flight, 10 s ACK timeout) and pushes that arrive while the app's JS
  is still starting are buffered and delivered after 'ready', since
  the watch's first outbox send races the run-state notification.
- pkjs-runtime.js: sandbox runner + Pebble shim (addEventListener,
  sendAppMessage, tokens, getActiveWatchInfo, openURL; timeline APIs
  stubbed). Lifecycle follows app_run_state notifications on endpoint
  52. In the browser the sandbox is a hidden same-origin iframe --
  window globals like localStorage are getter-only, so the shim
  bindings are installed with defineProperty -- with per-app-scoped
  storage and an XHR-over-fetch shim that retries failed cross-origin
  requests through a configurable CORS proxy (?pkjs_proxy=).
- config pages: openURL appends the return_to convention pointing at
  config-return.html, which posts the response fragment back to the
  page for the webviewclosed event.
- pbw.js extracts pebble-js-app.js; index.html registers installed
  apps with the runtime and adds a settings button that triggers
  showConfiguration.

Verified headless (node:vm sandbox) and in Chromium: BlobDB install,
watch-initiated AppMessage push delivered to JS, XHR fetch, and the
reply rendered by the C app on the emulated display.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Pi1WErefJ7c6kXodajm25M
Signed-off-by: Eric Migicovsky <eric@repebble.com>

Cloudflare Worker the emulator page falls back to when a JS app's API
call has no CORS headers. Origin-allowlisted, GET/HEAD/POST only,
credentials stripped both directions, internal hostnames refused.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Pi1WErefJ7c6kXodajm25M
Signed-off-by: Eric Migicovsky <eric@repebble.com>

Add the runtime modules and config-return page to site-dist and
apply.sh; document the PKJS architecture in the README.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Pi1WErefJ7c6kXodajm25M
Signed-off-by: Eric Migicovsky <eric@repebble.com>

Browsers block window.open on data: URLs, which is how Clay-based apps
deliver their settings pages. Decode the data: URL, rewrite Clay's
default pebblejs://close target to the same-origin return page, and
render the page in a modal iframe; the return page now posts to parent
as well as opener. Hosted config pages keep the popup + return_to
path. Verified with a Clay-style page round-tripping its settings
payload in Chromium.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Pi1WErefJ7c6kXodajm25M
Signed-off-by: Eric Migicovsky <eric@repebble.com>

JS-side activity (app start, fetch failures, geolocation denials) was
only visible in devtools; mirror it into the page's console panel.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Pi1WErefJ7c6kXodajm25M
Signed-off-by: Eric Migicovsky <eric@repebble.com>

A silent OS-level location denial or a doubly-failed weather fetch was
invisible; wrap the sandbox geolocation methods and log XHR/fetch
failures and proxy fallbacks into the page console.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Pi1WErefJ7c6kXodajm25M
Signed-off-by: Eric Migicovsky <eric@repebble.com>

Call the top page's geolocation rather than the sandbox iframe's
(removes the permissions-delegation variable), fall back to IP-based
city-level location when the browser provider fails (common when OS
location services are off), and support a ?loc=lat,lon override.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Pi1WErefJ7c6kXodajm25M
Signed-off-by: Eric Migicovsky <eric@repebble.com>

Touch: pebble_touch.c gains a browser injection path — the page writes
{seq, down, x, y} in display pixels with Atomics and an 8 ms
virtual-clock poll raises the touch IRQ on state changes, mirroring
the input-layer handler. Canvas pointer events drive it; verified in
Chromium by touch-scrolling the launcher.

Audio: the pebble_audio drain stub now mirrors every DATA sample into
a shared int16 ring with rate/volume/playing mirrors; the page drains
it into WebAudio on a 60 ms poll, scheduling buffers at a running
playhead. The context is created on the first canvas touch to satisfy
autoplay policies.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Pi1WErefJ7c6kXodajm25M
Signed-off-by: Eric Migicovsky <eric@repebble.com>

- The 32 MB SPI flash is saved to OPFS when dirty (15 s cadence,
  strided FNV change detection) and restored on the next boot, so
  installed apps and settings survive reloads; PebbleKit JS sources
  are persisted alongside in localStorage. Factory reset wipes both.
- The page boots automatically on load (?noauto restores the button);
  switching boards reloads onto the chosen machine.
- gabbro (getafix_dvt) is a first-class board option with v4.35.0
  firmware in the site bundle.
- dbgserial (UART2) gains a browser input ring behind a wasm-console
  device property, giving the console panel a working prompt.
- Sensors & phone panel injects battery, compass, tap and time-format
  QemuProtocol frames over the existing serial bridge.

Verified in Chromium: autoboot, install -> OPFS save -> reload ->
restore (no re-fetch, JS registry intact), and the dbgserial prompt
answering 'help'.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Pi1WErefJ7c6kXodajm25M
Signed-off-by: Eric Migicovsky <eric@repebble.com>

- pulse-console.js: full PULSEv2 client. Frame layer (0x55 flags, COBS,
  0x55<->0x00 transparency, CRC-32 residue check), PPP control FSMs for
  LCP and the reliable-transport NCP, and a stop-and-wait LAPB client
  for the TRAIN transport. Logs (push 0x5021 port 3, the 29-byte
  <c16sccQH record) render as [time] <lvl> file:line: message -- the
  qemu build is plaintext PULSE, not hashed, so no dictionary is
  needed. The console input line drives the dbgserial prompt over the
  reliable transport (port 0x3e20).
- phone-extras.js: notifications and voice. buildNotification
  serializes a 46-byte SerializedTimelineItemHeader plus attribute and
  action lists (status must be 0, payload_length exact) into a BlobDB
  insert on the notifs db; the default notification carries a Response
  action with canned replies so the Reply -> Voice path works.
  VoiceService accepts dictation session setups on endpoint 11000,
  counts the (silent) Speex frames on 10000, and on stop returns a
  one-sentence transcription from browser speech recognition with a
  typed-prompt fallback, echoing app_initiated flags and app uuid.

Verified in Chromium end to end: parsed log lines, a 'version' prompt
round trip, a notification banner with working action menu, and
Reply -> Voice dictation displaying the browser-provided transcript.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Pi1WErefJ7c6kXodajm25M
Signed-off-by: Eric Migicovsky <eric@repebble.com>

Auto-boot disabled the dropdown before it could ever be used, making
board switches impossible. The selector now stays enabled; changing it
reloads the page onto the chosen machine, which is the only way to
restart the emulator anyway. Verified in Chromium: switching from a
running emery to gabbro boots the round 260x260 machine.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Pi1WErefJ7c6kXodajm25M
Signed-off-by: Eric Migicovsky <eric@repebble.com>

The global key handler consumed Enter and arrows even while typing in
the install/console inputs, pressing Select on the watch instead of
submitting the field. Ignore watch-key events when focus is in a form
field, and blur buttons after clicks so the next Enter goes back to
the watch rather than re-clicking the button.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Pi1WErefJ7c6kXodajm25M
Signed-off-by: Eric Migicovsky <eric@repebble.com>

Ports the SDK's waf resource generators to JS so an app's images, fonts
and raw assets can be turned into an app_resources.pbpack client-side:
pbpack.py for the container, bitmapgen.py for PBI, png2pblpng.py plus
pebble_image_routines.py for the palettised PNGs, and font/fontgen.py
for PFO v3. PNG decode and encode are done here rather than through the
canvas so the output is identical under Node and in a worker; zlib comes
from the streams API.

FreeType is not available, so glyph rasterisation is delegated to the
host through a rasterizeGlyph callback -- canvas in the browser, and in
the test the golden font's own glyphs, which isolates the serialiser.

Two SDK behaviours are deliberately reproduced rather than corrected,
because matching waf's output is the point: bitmapgen._set_bbox()
transposes its columns back into rows before computing the right edge,
so empty right-hand columns are never cropped; and a font's table
offsets are relative to the sfnt header, which is not always at the
start of the file (the pebble-timer font carries a 260-byte prefix).

Validated against a golden waf build of pebble-timer on emery: the
pbpack container is byte-exact, 10 of 17 resources are byte-exact
including all four fonts, and the rest -- where the SDK's palette order
comes from a Python set and so cannot be reproduced -- decode to
identical pixels. Building the whole app from a clean checkout now
takes 2.3s under Node, and the resulting pbw runs in the emulator.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Pi1WErefJ7c6kXodajm25M
Signed-off-by: Eric Migicovsky <eric@repebble.com>

Paste a repo holding an SDK app into the emulator page and it compiles
client-side and installs what it built -- no SDK, no toolchain, no
server. Building coredevices/pebble-timer takes about four seconds once
the tools are cached.

Wires the compiler into the page: a repo URL box next to the install
one, a worker that survives across builds, and the codeload zip URLs a
repo (or a /tree/<ref>) maps to. GitHub does not send CORS headers on
codeload, so the fetch falls back to the pkjs proxy already used for
app JS.

The tools themselves (gzipped clang.wasm and lld.wasm, esbuild, and the
emery SDK pack -- 39 MB together) ship in web/tools/ and are cached in
the Cache API after the first build. apply.sh copies them, the page
modules and the vendored shims into a deploy, taking them from web/
rather than site-dist/ so they are not stored twice.

A build saturates every core, which starves QEMU: the watch would fall
far enough behind that the first BlobDB insert timed out and the install
failed outright. Give the emulator a moment before installing, and treat
a silent watch as retryable there rather than fatal.

Also fixes two things found by running it: the worker resolved the tools
directory against its own URL one level down, and Chromium rejects a
font whose sfnt header is not at the start of the file (pebble-timer's
is 260 bytes in) where FreeType accepts it.

Tested in Chromium against a deployed bundle: repo URL to a running app
in 13 seconds, PebbleKit JS included.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Pi1WErefJ7c6kXodajm25M
Signed-off-by: Eric Migicovsky <eric@repebble.com>